===================================================================
				M U G !

		MSDOS Utilities Graphic !nterface v1.20

		  Copyright 1997-2001 by Peter Watson
===================================================================

This is MUG! (MSDOS Utilities Graphic !nterface), a GS/OS NDA which includes the ability to read, *WRITE* and *FORMAT* MSDOS disks. These notes have lots of helpful hints for installing and using MUG! Please read them!

There is a list of changes at the end of this file.

**** Please read the 'MUG.Credits' file as well. ****
Hint: Hold down the Option key when pressing the 'Read Me' button.

Notice:
======
This program is SHAREWARE. That means you may copy it, and you are encouraged to give a copy to your friends, or upload it to online services. However, you must ensure that ALL files in the package (see the list at the end of this document) are included, WITHOUT MODIFICATION, when making a copy for others.

You may use MUG! for a period of two weeks. At the end of that time you are required to send the SHAREWARE fee to the address below, or to erase any copies of MUG! that you may have. When I receive your SHAREWARE fee, you will be registered as a legitimate user. This will entitle you to support, I will send you the latest version of MUG! by email (if you don't already have it), and any suggestions you make are *much* more likely to be acted on!

Registered users are entitled to use any future (non-commercial) upgrades for free. To request an upgrade directly, send $5 cash to the address below. When registering, please mention the version number of MUG! as shown in the 'About' dialogue.

Payments in overseas currencies made by personal cheques are mostly eaten up by Australian bank charges. Australian or US cash is best. In fact, if you send cash, you get a discount of $5 since I don't have to pay bank fees!

==================================================================
=== BlueDisk Owners ===

If you received the original MSDOS Utilities as part of the software included with the BlueDisk interface created by Joachim Lange of ///SHH Systeme, then you automatically became a registered user of the original MSDOS Utilities. As such, you are entitled to receive MUG! for the UPGRADE price.

==================================================================

Address for shareware fees, upgrade fees and general correspondence:

	Peter Watson
	13 Ilios Close
	Forest Hill  Vic  3131
	Australia

Comments by email are welcome - my InterNet address(es):

	paw@acslink.net.au
	paw77@hotmail.com

If you include your email address (InterNet, Delphi, Genie, CompuServe, AOL) when registering, I can respond much more easily! In fact, if there is a newer version available you'll receive it via email.

Read the 'MUG.Credits' file to see the benefits of paying for shareware!

==================================================================

The SHAREWARE fee for this disk is :-
	  US$20.00
	AUS$20.00

*** Non-Australian users: You get a $5 discount for cash since I don't
*** have to pay the bank fee for cashing international checks!

The upgrade fee for registered users of the MSDOS Utilities is :-
	  US$15.00         (or US$10 for cash!)
	AUS$12.00

If you do not already have the MSDOS Utilities (a collection of MSDOS-style command shell utilities, with a few extra features over MUG!, and including a working command shell for use with any other shell (filetype "EXE") commands you have or find), then you can receive them at the same time for an additional $5.00.

==================================================================
All files in this package are Copyright 1997-2001 by Peter Watson,
except for parts that are Copyright 1987-1994 by ByteWorks (see below).
==================================================================

Table of Contents
-----------------
Introduction
Hardware Requirements
Software Requirements
Installation
Preferences
Special 'Option Key' features
Miscellaneous Notes
- Keyboard equivalents
--- Main Window
--- General Text Display Window
--- Preferences Window
--- Rename Window
--- Attributes Window
--- Format Window
--- Get Files Window
--- Save Files Window
--- Thermometer Windows
- Disk Sizes and Types
- Windows 95, VFATs and Long File Names
- Applied Engineering PC Transporter (AEPCT)
- MSDOS Hard Disk Partitions
- AEPCT MSDOS Partition Files
- Copying from MSDOS to MSDOS
- Default Translation of File Contents
- File Name Translation
- MSDOS Volume Names and the MSDOS FST
- Auto-Disk Eject
- Disk Interleave
- Compressed Disks Not Supported
- Debug Feature
MUG! Internal Limitations
Known Problems
The Future
The Past
Package Contents
Legal Stuff

=================================
=== Introduction

MUG! is an integrated set of utilities that allows files and directories on MSDOS disks to be read, *WRITTEN*, listed, deleted, renamed, etc. You can also copy, format and (re)label disks. Any size disk should be supported (except for formatting), including partitioned hard disks and Applied Engineering PC Transporter MSDOS partition files.

What are the benefits of MUG! over Apple's MSDOS FST? For reading from MSDOS disks, not a lot - except that the MSDOS FST can't handle disks containing long file names created by Windows 95, or partitioned disks (eg. Zip or SyQuest cartridges) or Applied Engineering PC Transporter (AEPCT) MSDOS partition files, and it does not do any text file conversion when copying files. Well, maybe there *are* a few benefits after all!

On the other hand, Apple does not support writing to MSDOS disks in any way (eg. copying files to MSDOS disks, formatting disks, renaming files, etc) - all items supported by MUG! Also, the MSDOS FST requires GS/OS System 6.01, (using more memory and disk space at boot time), while MUG! will work with System 6.0.

I am reasonably confident about MUG!, but as it has not been tested on a complete range of disks and files I am not willing to swear that it is bombproof. To put it more bluntly, you are using MUG! at your own risk. If you are not prepared to take the risk, don't use MUG!. Having said that, I use it and my hard disk is still in one piece! And neither Norton's Utilities nor the MSDOS ScanDisk utility complain about MSDOS disks created by MUG!


=================================
=== Hardware Requirements

MUG! itself requires about 150K of hard disk, plus another 50K or so for text documentation and preference files.

It may be possible to run MUG! on a stripped down system with 1.25Mb of RAM. In practice you will almost certainly require 1.5Mb and most probably 2Mb of RAM to comfortably run System 6, a working set of extensions and DA's, and MUG! itself. Even though MUG! tries to minimise its memory footprint when not in use (for example, by unloading resources and releasing buffers), when executing it can require a lot of memory for working storage.

MUG! was developed on a system using an Apple II 3.5 Disk Controller with an Apple 3.5" FDHD 'SuperDrive', as well as a 100Mb Zip drive. It's predecessor (the MSDOS Utilities) has been tested with an Applied Engineering High Density drive attached to Apple's controller card, with 5.25" and 3.5" TransDrives attached to an Applied Engineering PC Transporter (AEPCT), with MSDOS drives attached to a BlueDisk interface, and with 100Mb Zip and 44Mb and 105Mb SyQuest drives formatted for MSDOS (attached to Apple High Speed SCSI controller or RamFast interface cards). Many people are successfully using Floptical drives, usually using RamFast SCSI controller cards.

Any MSDOS SCSI disk drive *should* be supported. In fact, so should *ANY* disk drive that is capable of reading a block from a disk formatted for MSDOS. If you are unsure, try using a disk zap utility to read block 0. If you do not get an I/O error, then MUG! should work with it! The only problem is that in general MUG! cannot format hard disks. However, there is inbuilt support for formatting 21Mb Floptical disks and 100Mb Zip disks.

One reported exception seems to be the FDC-10 card, which uses custom drivers that work in ProDOS 8, but not under GS/OS. I don't have access to one of these cards to allow me to check it out.

MUG! will also work with PC Transporter MSDOS partition files (acting as an MSDOS hard disk) on a GS/OS hard disk.

MUG! will *not* be able to access MSDOS disks if you only have an Apple or compatible 800K drive. Even with a PC Transporter card this is still true, although an 800K drive attached to a PCT can read and write MSDOS disks while running MSDOS on the PCT. This is a limitation of the Applied Engineering drivers provided for GS/OS. The only exception to this rule is with 800K MSDOS disks created using the PC Transporter, which are not very common!

Using Apple's FDHD SuperDrive and controller card, a 1.44Mb High-Density disk formatted as 720K on a MSDOS machine will not be recognised as a formatted disk. This is a restriction of the drive and/or controller card, which also applies with these types of disks in a Macintosh. A similar restriction *may* apply to other drive and/or controller card combinations.

-- Performance note --

MUG! was written for functionality, not speed. Nevertheless it performs reasonably well under most circumstances. Very large hard disks will slow it down (especially noticeable for directory listings) - the FAT table becomes huge!

The other commonly reported problem is very slow writing to MSDOS floppy disks. While MUG! is slower than GS/OS for writing, the real culprit is almost always the use of pre-formatted MSDOS disks. These are formatted with an interleave of 1:1, which is acceptable for reading but painfully slow for writing.

There are two possible courses of action. Firstly, for occasional disks obtained from elsewhere, you can simply live with the delay. Secondly, for floppy disks written to frequently, you should use the MUG! format option to reformat them at a 2:1 interleave -- do NOT check the 'Quick format' box!


=================================
=== Software Requirements

The only software requirement is GS/OS System 6.0 or later.

Although not required, the MSDOS FST can still be useful. When combined with MUG! it allows you to copy files between two MSDOS disks (or between two directories on the same disk) without having to copy via a GS/OS disk first. However, that the MSDOS FST has trouble with hard disks and disks containing long file names, which can limit the usefulness of this option.

See the note below about problems that may occur if Eric Shepherd's ListPatch601 patch program is also installed.


=================================
=== Installation

Simple!

Copy the file named MUG.1.20 to the 'Desk.Accs' folder inside the 'System' folder of your boot disk. You should also copy the files MUG.ReadMe and MUG.Credits to the same place to allow them to be used as "help" files, although MUG! can run without them if you are short on disk space.


=================================
=== Preferences

Pressing the 'Preferences' button displays a window allowing you to set default values for several options. The preferences are read from a file named 'MUG.Preferences' located in the same directory as the MUG! NDA file (normally the 'Desk.Accs' directory). If the file is not found, a new preferences file containing the default preference values will be created.

Press the 'Save' button to save your preferences for the future. Press the 'Use' button to change the values until the next time that MUG! window is opened. Press the 'Cancel' button to leave the values unchanged.

The 'More Preferences' button displays a second window containing additional preferences which do not fit into the first window. Pressing this button again switches between the first and second windows. You may Save, Use or Cancel all your changes from either window.

The various options are explained below.

-- Default MSDOS Device Number --

If you leave this field blank, there will be no default device.

If you enter a '0' (zero), the default device will be the PC Transporter file.

If you enter any other number then when the "Available Disks:" window is displayed for the first time, the disk drive with that device number will be highlighted, allowing you to simply press the 'return' key to select it. On subsequent operations, MUG! tries to remember the last device used.

Remember, device numbers can change depending on the drives and/or partitions that are online when GS/OS is booted, on which device you boot from, and on the order of the device drivers in the 'system:drivers' directory of your boot disk.
Nevertheless, for many people, device numbers rarely change and this default provides a useful function.

MUG! is distributed with a simple program called "Online" which will display the device number and some other information for each device recognised by GS/OS. If you have more than one screen of devices, pressing (almost) any key will pause the program. Press it again to allow the program to continue. At the end of the display, press a key to exit the program. For users of command shells such as ORCA/M and GNO/ME, change the filetype to EXE ($B5) to allow the program to execute as a shell utility and bypass the final keypress.

There is also a utility called "Online2Disk" which is graphic-based version of "Online" which saves the information to a disk file. Simply double-click on Online2Disk in the Finder.

-- Default Hard Disk Partition Number --

If you are using an MSDOS partitioned hard disk (most likely a removable drive such as a Zip or SyQuest cartridge), then there may be up to 4 partitions. By default, MUG! will try to read the partition marked as 'bootable' (there is only allowed to be one such partition). By changing this option you can read from one of the other partitions.

If you enter a '0' (zero), the partition marked as 'bootable' will be used.

If you enter a number from 1 to 4 then one of the other partitions will be read.

For further information, see 'MSDOS Hard Disk Partitions' below.

-- Add/Strip linefeeds while copying --

MSDOS text files mark the ends of lines using the two characters 'return' and 'linefeed'. Apple files use only the 'return' character. (And UNIX files use only the 'linefeed' character!)

If this option is checked, then MUG! will add linefeed characters after return characters to files copied to MSDOS disks, and will strip them from files copied to GS/OS disks. The files will be given a file type of 'TXT' ($04).

If this option is not checked, then no file translation is performed, and files copied to GS/OS are given a file type of 'BIN' ($06).

However, if the 'UNIX text file translation' option is also checked, the action of this preference becomes 'Add/Strip *returns*' since UNIX files use the linefeed character in place of the return character. The other difference is that there is no check that return characters are actually followed by linefeed characters - all returns are stripped.

For further information, see 'Default Translation of File Contents' below.

-- UNIX text file translation --

This option simply changes the action of the 'Add/strip linefeeds' option to that of adding and stripping 'return' characters. This allows processing of text files following the UNIX convention of marking the end of a line with a linefeed (aka newline) character. If the 'Add/strip linefeeds' option is not checked, then this option is ignored.

(Since many GS people these days also work with UNIX or Linux systems, this seemed like a reasonable request to support! :-)

-- Automatic text file recognition --

The 'Add/Strip linefeeds' option has the disadvantage that it applies to all files, no matter what the type or contents. While you can hold down the Option key to toggle the 'Add/Strip linefeeds' status for a particular file, this is not very convenient in the long term, or if you are copying several files of mixed types.

The solution is automatic recognition of text files when the 'Add/Strip linefeeds' option has NOT been checked. For copying from GS/OS to MSDOS, files of type TXT ($04) and SRC ($B0), with any auxtype, are considered to be text files. For copying from MSDOS to GS/OS, files with certain filename extensions are considered to be text files and are saved with type TXT ($04). In both cases, the files will be processed as though the 'Add/Strip linefeeds' option was set.

The list of text filetypes recognised during MSDOS to GS/OS copying is based on the list used by the MSDOS FST for a similar purpose. The following extensions are recognised:

.TXT		.ASC		.BAT		.DOC
.DOX		.LST		.ME		.SRC
.ASM		.PAS		.COB		.FOR
.C		.H		.HTM		.RTF
.BSQ

The .DOC extension is a bit of a problem. Once upon a time (and sometimes even today), this type indicated a text "documentation" file used in a similar way to a "READ.ME" file. However, more commonly this type is used to indicate a Microsoft Word word processing file. The bad news is that any attempt to copy an MS Word file will leave the copied file unreadable. The good news is that the file would have been unreadable on a GS anyway! Of course, if you really need to copy such a file (perhaps to take to a Mac or upload to the Net), you can disable the 'Automatic text file recognition' option while doing the copy, or simply hold down the Option key until the copy starts.

Technical types who have access to a resource editor can add or delete values 
from the file extension list by modifying the resource containing the list. The resource type is $801D (rCString) and the ID is 0001. The string simply consists of a continuous sequence of three character, blank-padded file extensions. New entries can be added on any three-byte boundary, but don't forget to ensure that new entries are also exactly three bytes long. For example, the resource string "TXTC  DOC" contains entries for three extensions: '.TXT', '.C' and '.DOC'.

-- Default to 'MSDOS to GS/OS' copying --

If this box is checked, the copy 'To GS/OS' radio button will be selected whenever MUG! is opened.

If this box is not checked, the copy 'To MSDOS' radio button will be selected whenever MUG! is opened.

-- No prompt when overwriting files --

If this box is checked, no warning will be given when a file with the same name exists in the target directory of a copy.

If this box is not checked, MUG! will offer several choices such as deleting the original file, renaming the new file, skipping the file or cancelling the copy.

In either case, when copying from MSDOS to GS/OS, the first file (only) may still get a 'Replace' or 'Cancel' prompt message from GS/OS. This is a standard message which I cannot disable. Sorry!

-- Sort MSDOS file selection lists --

If this box is checked, MSDOS file selection lists are sorted alphabetically (ignoring upper and lower case distinctions).

If this box is not checked, MSDOS file selection lists will show the files in the same order as they appear in the original MSDOS directory.

This option has no effect on the order of files displayed by the 'Dir List' function, which (for now, anyway) always displays the files in the same order as they appear in the MSDOS directory.

-- Hide hidden/system files in lists --

If this box is checked, MSDOS file selection lists will not show files which have the Hidden or System attributes. These attributes serve a similar function to the GS/OS 'invisible' file access bit. Note that these atributes are ignored for directories, which will always be displayed.

If this box is not checked, MSDOS file selection lists will show all files.

This option has no effect on the display of files by the 'Dir List' function, which always displays all the files in the MSDOS directory.

-- Disable auto-eject of disks --

If this box is not checked, MUG! will attempt to auto-eject disks when a disk swap is required during a disk copy.

If this box is checked, MUG! will not attempt to auto-eject disks, but will prompt the user to swap disks manually.

Note that in either case, with most drives MUG! should recognise that a new disk has been inserted and continue automatically.

-- PC Transporter Hard Disk Volume Paths --

MUG! can read and write to the GS/OS file(s) that the Applied Engineering PC Transporter uses to simulate MSDOS hard disk partitions. If you specify the GS/OS pathname of this file in the 'File 1' box, then an additional 'disk' will appear in the 'Available Disks' window when choosing disks and files. If the 'partition is larger than 16Mb, then there will be two files under GS/OS, and the pathname of the second file should be placed in the 'File 2' box.

Note that you cannot use the two file boxes to specify two different partition files.

For further information, see 'AEPCT MSDOS Partition Files' below.


=================================
=== Special 'Option Key' features

Pressing the Option key at certain times provides additional options:
- when selecting a directory list, MUG! asks if you want a 'detailed' display
- when viewing files, MUG! asks whether you want to view in normal text mode,
   hexadecimal data dump mode, or verify mode (reads but doesn't display)
- when copying files, temporarily swap the 'Add/strip linefeeds' preference
- when pressing the 'Read Me' button, Mug! displays the Credits file


=================================
===
=== Miscellaneous Notes
===
=================================

------------------------------
--- Keyboard equivalents
------------------------------

Most buttons and controls have keyboard equivalents. If there is no name edit area in the window, then you don't even need to press the Command (Open-Apple) key. With one exception, the key may be upper or lower case.

-- Main Window --

Return		Dir List
V		View File
R		Rename
D		Delete
P		Preferences

C		Copy
M		To MSDOS
G		To GS/OS
N		New Folder
A		Attributes
?, /		About

I		Disk Info
L		Label
F		Format
X		Disk Copy
H		Read Me

-- General Text Display Window --

Return		Continue
Esc		Continue
s		Save
Shift-P 	Page Setup (must be upper case)
p		Print (must be lower case)

-- Preferences Window --

Return		Save
Esc		Cancel
Apple-U 	Use
Apple-M 	More Preferences

-- Rename Window --

Return		OK
Esc		Cancel
Apple-R 	Replace
Apple-S 	Skip

-- Attributes Window --

Return		Save
Esc		Cancel
R		Read Only
H		Hidden
S		System
A		Archive

-- Format Window --

Return		Cancel
Esc		Cancel
Apple-F 	Format
Apple-Q 	Quick format (skip low-level format)
Apple-G 	Use GS/OS initialization dialogue

-- Get Files Window --

Return		Open
Esc		Close
Apple-D 	Disks
Apple-. 	Cancel
Apple-A 	Accept

-- Save Files Window --

Return		Save
Apple-O 	Open
Esc		Close
Apple-D 	Disks
Apple-. 	Cancel
Apple-N 	New Folder

-- Thermometer Windows --

Apple-. 	Cancel

------------------------------
--- Disk Sizes and Types
------------------------------

Testing has been performed on 720K and 1440K 3.5" disks (and 800K MSDOS disks created using the PC-Transporter), on 360K 5.25" disks attached via an Applied Engineering PC-Transporter, and on 100Mb Zip and 44Mb and 105Mb SyQuest cartridges (with partitioning). Several people are using Floptical drives, mostly attached to RamFast SCSI cards. There is every reason to believe that 1200K 5.25" disks and 1600K and 2880K 3.5" disks should work correctly, but at present they have not been tested. Lastly, PC-Transporter hard disk partitions (in the form of ProDOS files) are supported.

In general, the size (capacity) of a disk should not matter with the exception of 'Format', which needs to know about the device geometry. You should be prepared for slower access to larger disks. Many more blocks need to be read/written for the larger FAT and directory areas. Also, scanning the FAT for free blocks takes longer, which is particularly noticeable at the end of a directory listing on a large hard disk. Maybe one day I'll rewrite the code in assembler to speed it up, but it's a low priority as the speed is not an issue on floppy disks. (And some quick and dirty trials showed little improvement!)

In general, MUG! cannot format large MSDOS disks, that is, larger than 2880K. The problem is that MUG! is unable to build the required partition table. Two exceptions are supported, namely 21Mb Floptical disks and 100Mb Zip disks, which have special code to handle them. Note that when selecting one of these last two devices from the device selection list you should choose the first SCSI device in the list that applies to the device. For example, devices .APPLESCSI.HD02.00 and .APPLESCSI.HD02.01 may refer to two partitions on your second SCSI drive - you should select the first when formatting it.

MUG! can read and write (but not format) PC Transporter MSDOS hard-disk partition files on a GS/OS hard disk. See the extra explanation below for details of how to use this feature.

------------------------------
--- Windows 95, VFATs and Long File Names
------------------------------

Windows 95 (actually, it was Windows NT!) introduced the concept of the VFAT file system and long filenames with a maximum of 255 characters -- a 'slight' increase over the original 11 characters!  MUG! will display long filenames in directory listings, and will always correctly handle disks and directories containing long filenames. At present, however, full support for long filenames is not present.  In particular, this means that files you create will have short names, and the file selection dialogue displays short filenames.

However, the 'Rename' function *can* create long filenames, if appropriate.

Warning: The GS/OS MSDOS FST gets confused by disks containing long filenames. It thinks they are volume labels!

To reduce the risk of problems for people who do not have access to Windows 95 systems or who use the GS/OS MSDOS FST, the Rename option will not automatically create long filenames unless one or more of the following conditions exist:-

- The specified new name is too long or contains otherwise illegal characters
- There is an existing long name for the file

Note: A short name entry will be automatically generated from the long name. The generated name generally follows MicroSoft's (fairly complicated) rules for shortening long names.

Note: You can display long filenames using the 'Directory' function to determine the correct short name to use with the other functions. Long names (if any) are displayed on the right of the screen. However, keep in mind that if Windows 95 has processed the file since you last looked at it on the IIgs, then the 'generated' short name may have changed - even though the long name remains the same!

The important thing to remember is that for compatibility with earlier versions of MSDOS, all Windows 95 utilities *must* create short filenames along with the long name. Typically a file named 'Long Name.txt' would have a short name that looked like 'LONGNA~1.TXT'. Also, all utilities must be able to read files using a short name only. What this means is that you still have full compatibility with all of the new Windows 95 applications, even if you create files without long names.

------------------------------
--- Applied Engineering PC Transporter (AEPCT)
------------------------------

To use drives attached to the IIgs through an AE PC Transporter, remember to activate the AEPCT ProDOS drivers using the PCTSWAP program before invoking MUG! (otherwise the drives cannot be 'seen' by GS/OS). You should also deactivate them again (or the 5.25" drives at least) before running or returning to the Finder - otherwise the continuous "polling" of the drives will slow down your system dramatically. If you have not already installed the AEPCT ProDOS drivers, you will need to do so using the PCTINSTALL program.

The AEPCT ProDOS drivers were designed for 360K 5.25" drives. They will operate with 720K 3.5" drives attached to the PCT, but only the first 40 tracks (ie. 360K) will be usable. (720K drives work correctly from the MSDOS side of the AEPCT because different drivers are used.) In practice, this means that the root directory is always readable, and as long as the used space does not go over about 320K everything else should work reasonably well also. Two major casualties are the 'Format' and 'DiskCopy' functions which need to be able to "see" the entire disk. However, you *can* perform a 'Quick' format, since that only erases the root directory and FAT tables.

The AEPCT does not support high-density (1200K 5.25" and 1440K 3.5") drives.

See the explanation below for details of how to read and write to a PC Transporter MSDOS hard-disk partition file.

------------------------------
--- MSDOS Hard Disk Partitions
------------------------------

MUG! is able to handle normal MSDOS hard disk partitions (SCSI partitions are handled outside the control of MUG!). Note that a SCSI drive may theoretically have more than one MSDOS 'SCSI partition', each containing up to 4 'MSDOS partitions' (the schemes are not mutually exclusive).

If the drive is partitioned, and you don't specify a partition number, MUG! will try use the partition that is marked as 'bootable' in the partition table.

Having said all that, the problem for most people is getting past the Finder! During initialization, the Finder usually complains about an unrecognised disk format and offers options to format or eject the disk. If the disk is "ejected", then GS/OS no longer acknowledges that the disk/partition exists, and thus MUG! cannot "see" the disk either. Possible workarounds include using the SetStart Control Panel to boot directly into a "shell" environment such as ORCA, GNO/ME or COMMAND.COM. From there, a GUI application program can be executed to allow access to NDAs. For removable drives such as Zip or SyQuest drives, you can boot with a normal GS/OS disk in the drive, then swap disks while running an application program.

At present, MUG! will handle partitions numbered 1 to 4 on a device (there can only be 4 normal partitions per device) by setting the default partition number in the Preferences. An interesting point is the order that partitions are numbered! I have seen partition tables with the partitions numbered in 1-2-3-4 order, and others in 4-3-2-1 order! Since MUG! must assume one particular order, if you think that a hard disk is partitioned for MSDOS, you should try *all* the partition numbers from 1 to 4 before assuming there is nothing there.

It is possible for a partition to be an 'extended' partition - which basically points to other partitions within itself. MUG! at present will only the read the *first* partition pointed to by an extended partition table entry. However, you should note that this feature has not yet been tested!

Note that MUG! cannot format MSDOS partitioned disks, with the exception of 100Mb Zip disks (which are created with a single large partition).

------------------------------
--- AEPCT MSDOS Partition Files
------------------------------

MUG! can read and write (but not format) the GS/OS file(s) that the Applied Engineering PC Transporter uses to simulate MSDOS hard disk partitions.

The preferences must have been set to contain the pathname(s) of the PC Transporter MSDOS hard disk partition file(s). If the logical MSDOS partition is larger than 16Mb, then the Applied Engineering software will have created two physical GS/OS files. In this case, the pathname of the second file must be placed on the second preferences line. If you don't own a PC Transporter card, or don't have an MSDOS partition file on your GS/OS hard disk, then you don't need to worry about this feature.

An example pathname might look like :

File 1:  /MY.HARD.DISK/AEPCT.Files/MSDOSVOL1

If there are two partition files, the pathnames might look like :

File 1:  /MY.HARD.DISK/AEPCT.Files/MSDOSVOL1
File 2:  /MY.HARD.DISK/AEPCT.Files/MSDOSVOL2

** Warning **: The partition file(s) must NOT be 'locked', or MUG! will be unable to open the file, even for 'read-only' activities. The disk that the file is on may be write protected, however.

** Note **: Device number 0 is used to specify an MSDOS partition file as the default device in the preferences.

** Note **: The 'Format' and 'DiskCopy' options do not support MSDOS Partition files.

------------------------------
--- Copying from MSDOS to MSDOS
------------------------------

MUG! assumes that only one MFM-capable drive exists. Thus you cannot copy from one MSDOS disk to another, except via a GS/OS disk. Note that this should not normally be a problem as most directory information is preserved when copied to GS/OS (the exceptions are attributes such as Read-Only, etc.), and the information can be copied back to the MSDOS disk with the file. On the other hand, directory information *is* lost when copying to MSDOS. For example, a file copied to MSDOS and back to GS/OS loses its filetype and creation dates.

'Diskcopy', in particular, is specifically designed to be a single drive copy, as there are alternatives which can perform a two-drive copy of an 'unknown' disk type.

***Exception***: Using System 6.01 and Apple's MSDOS FST, it is possible to read MSDOS disks in one drive and write to MSDOS disks in another. This is because the MSDOS FST allows the source disk to appear to MUG! as a 'GS/OS' disk. Note that in this case you should copy files with the Add/Strip Linefeeds option disabled to ensure that extra line feeds are not added unnecessarily. Although attributes such as 'Read-Only' are lost, they may be corrected with the 'Attributes' option.

------------------------------
--- Default Translation of File Contents
------------------------------

The default copy mode is 'binary' mode. This means that no translation is performed on contents of files when transferred in either direction.

The alternative is 'text' mode. In this mode, files copied to MSDOS will have a linefeed added after each carriage-return character, and files copied from MSDOS will have linefeed characters after carriage-return characters removed. Also, when copying *from* MSDOS, the file will be terminated after the first 'control-Z' character (the end-of-file character).

If the 'UNIX test file translation' option is checked in the Preferences dialogue, then for 'text' files (all) carriage-return are added or stripped, and linefeed characters are preserved. There is no difference for 'binary' files.

No other translation of contents is done. For example, an AppleWorks file does not become readable by MS Word.

If text mode file translations are required, check the 'Add/Strip linefeeds' option in the Preferences dialogue. Pressing the Option key while clicking on the Copy button swaps the effect of the 'Add/Strip linefeeds' option for that copy operation. However, the easiest way of all is to check the 'Automatic text file recognition' Preference option, which automatically detects the type of file based on the MSDOS file extension (eg. '.TXT') or GS/OS filetype.

Files copied from MSDOS to GS/OS are given a filetype of TXT for 'text' copy mode, otherwise they are given a filetype of BIN for 'binary' copy mode.

------------------------------
--- File Name Translation
------------------------------

Most filenames copied *from* MSDOS can be used in GS/OS. If a file is copied from MSDOS and no target filename is specified, 'Copy' will attempt to make the MSDOS filename suitable for the target file system. For HFS disks, no conversion is required! For ProDOS, if the filename contains special characters (such as '$' or '_'), these will be replaced by '.' characters (runs of which will be shortened to single '.' character).  If the resulting name does not begin with an alphabetic character, it will be prefixed by 'A'. This name conversion is performed by the GS/OS 'JudgeName' system call, if possible.

Files copied *to* MSDOS with no target name specified will have any illegal characters (such as from HFS filenames) in the GS/OS filename removed - in particular, this includes any '.' characters. The resulting name is shortened (if necessary) to eight characters plus the first three characters of the name after the last '.' character, by saving the first five and the last three characters. If there is no '.' character, the name will be shortened to the first eight plus the last three characters. The aim is to preserve the extension when dealing with a series of filenames like FILE.1, FILE.2, etc.

Note that long names will be shortened, even when writing to disks that will be used on Windows 95 systems (which support long names). If you need the long name, use the 'Rename' option to create a long filename.

Filename Translation Examples:

GS/OS filename	        MSDOS name		Notes
--------------	        ----------		-----
-WXYZNAME      	        WXYZNAME.              	No change
-FILENAME.TXT  	        FILENAME.TXT   		No change
-FILENAME.TEXT 	        FILENAME.TEX   		'Extension' was truncated
-TOM.DICK.HARRY	        TOMDICK.HAR    	       	Extra '.' stripped
-LONGFILENAME  	        LONGFILE.AME   	       	Keep last three characters
-LONGFILENAME.1	        LONGFAME.1     	       	Compress, keeping 'extension'
-FILE FROM HFS 	        FILEFROM.HFS   	       	Illegal characters stripped

------------------------------
--- MSDOS Volume Names and the MSDOS FST
------------------------------

The MSDOS FST has a "feature" to be aware of now that it is possible to write to MSDOS disks. Since MSDOS disks are not guaranteed to have an explicit volume label, the MSDOS FST creates an internal volume name whenever an unlabelled MSDOS disk is found. This generated name is based on a checksum of the root directory. The volume name is important since it allow the MSDOS FST to detect a switched disk (in case the hardware doesn't signal it).

This system worked well when it was impossible for the root directory to change without taking the disk to an MSDOS machine. Now that MUG! can modify the root directory on a disk, you may see the rather weird effect that ejecting and reinserting a changed disk causes the volume name to change in the Finder!

Since the MSDOS FST is unlikely to be updated, this just has to be regarded as one of the quirks of life that we have to live with.

------------------------------
--- Auto-Disk Eject
------------------------------

Both Format and DiskCopy options will automatically eject disks before and during the command operation. For some drives this is silly (for example, 5.25" drives), and for others it can even be a downright nuisance or worse (for example, some floptical or other SCSI drives). This function can be disabled using the Preferences dialogue.

------------------------------
--- Disk Interleave
------------------------------

If access to 3.5" MSDOS disks seems unreasonably slow, it may be that they were pre-formatted using a 1:1 interleave. You should reformat the disks using a 2:1 interleave (eg. using the Format 'Interleave' option). It may even be necessary to use a larger interleave value.

Note that the interleave value is ignored when formatting Zip disks using Apple's SCSI driver. I have no information on the behaviour of other drivers.

------------------------------
--- Compressed Disks Not Supported
------------------------------

This note will be obvious to some people, but it is worth mentioning anyway. Software exists in the MSDOS world to increase the space available on disks by compressing the data at the block level on disk. For example, 'Stacker', and MSDOS v6 and later. The former can even create "Stacked" floppy disks. These are *not* usable by MUG! as the data within blocks is not understandable.

------------------------------
--- Debug Feature
------------------------------

MUG! has a hidden feature that I may ask you to use to assist me to debug MUG!'s handling of unusual MSDOS disks. If you click on the word 'Disk' in the 'Disk Tools' title, you will be asked about the amount of disk debug information you want written to a GS file. Click on 'Long' for the long (512K) version, or 'Short' for the short (16K) version. If you click on 'Cancel', you will return to the main menu, otherwise the usual MUG! dialog for selecting a device will appear. When you select a device, a GS/OS standard file prompt will ask for the name (the default is 'MUG.Debug') and location of the output file. This file must be on a GS/OS disk. When you click on the 'Save' button, MUG! will write debugging data to the output file. This file can be emailed to me (it contains only printable characters) or copied to a floppy disk and snail-mailed to me.

For emailing, especially for the long format file, there may be some benefit in using ShrinkIt to compress the file, followed by BINSCII or GSCII+ to convert the compressed file back to a printable format again.


=================================
=== MUG! Internal Limitations

- Maximum of 32 disk devices in device lists
- Maximum of 120 clusters per subdirectory (nearly 1000 files!)
- Displaying files requires enough memory to load the entire file at once
- MUG! preserves but doesn't act on the hidden, system and read-only attributes
- PC Transporter hard disk files must remain online while the MUG! window is open
- The ListPatch601 patch for System 6.0.1 can cause MUG! to lock up
- At present, new "long" filenames are limited to 31 characters when renaming
- MUG! has not been tested on devices with a sector size of more than 512 bytes, although most functions should work


=================================
=== Known Problems

-- Formatting --

Apple's 3.5" Disk Controller seems to have a problem when it does a low-level format on a double-density MFM disk (ie. 720K). The format process actually completes, and the system doesn't crash, but you can no longer access *any* 3.5" disks! You must eject the disk and do a 'three-finger-salute' reboot (a normal shutdown does not seem to be enough), after which you can finish the original operation. For example, 'Diskcopy' will format the target disk if it is unformatted or the wrong size (eg. 800K). After the format, the program fails as described above, but after rebooting the copy proceeds as the disk is now formatted. 'Format' similarly fails after the low-level format, but after rebooting you can use the 'Quick format' option to write the empty directory, etc. Note that this format problem can be seen with other programs, not just MUG!

The problem *DOES NOT* occur with 1.44Mb (high-density) disks - this is not really surprising as they are already MFM-formatted for both Apple and MSDOS use. Note that 'Diskcopy' will copy 720K disks just fine if the target disk has previously been formatted for 720K.

-- ListPatch601 --

If Eric Shepherd's ListPatch601 patch to the System 6.0.1 List Manager is installed, then after using keyboard navigation in a MUG! list any attempt to 'reshow' the list with changes (using the 'NewList2' tool call) will hang or crash into the monitor.

List controls will still work perfectly if only mouse actions occur.


=================================
=== The Future

Since this program is based on the 'MSDOS Utilities' suite of programs, most of the serious development has already been done. But there are still several rough edges and "nice bits" that I'd like to add. As always, time will be the issue!


=================================
=== The Past

v1.00	The first public version of MUG!

V1.00 was crashing on leaving ProDOS 8 programs invoked from the Finder, which I don't normally use! Then one of my beta testers tells me *after* it is reported that "Oh yeah, that happens to me too, but I didn't connect it with MUG!".

v1.01	The first public version of MUG! that didn't crash!
v1.10	Skipped to avoid confusion with v1.01.
v1.20	- Ability to format 100Mb Zip disks
	- Recognises text files by the file extension or GS/OS filetype
	- Directory dates use format from Control Panel for mm/dd or dd/mm
	- Added Online2Disk utility
	- Shareware "annoying reminder" dialogue removed
	- "View File" automatically views as text unless the Option key is
	  pressed to show the 'Text', 'Hexadecimal', 'Verify files' prompt
	- "Copying" message notes if 'text' files are being copied
	- Static memory usage reduced
	- Miscellaneous minor user interface adjustments
	- 50% larger subdirectories (number of clusters) supported
	- Fixed problems calculating block addresses for large (eg. Zip) disks
	- Directory is no longer corrupted after multi-file space problems
	- Viewing files didn't always free buffers after errors, but would free
	  a buffer it didn't have in 'Verify' mode (very bad with several files)
	- Viewing text files with many tabs no longer overwrites memory
	- Several other minor bugs squashed
	- New preference settings
		+ Recognise text files by the file extension or GS/OS filetype
		+ Convert UNIX text files (lines ended by linefeed, not return)
		+ No prompt before overwriting files
		+ Don't sort MSDOS file lists
		+ Hide 'hidden' and 'system' files in file lists


=================================
=== Package Contents
=============
MUG.1.20  	The MUG! NDA file (and version number)
MUG.ReadMe	You're reading it!
MUG.Credits	You and I both can thank these people!
Online		Displays device numbers (and other details) for devices
Online2Disk	Saves Online-style device information to disk


===================================================================
=== Notice

These files are SHAREWARE. That means you may copy them but you may not sell them. Bona-fide User Groups may charge their usual copying fee only - up to $7.00. The files may be included on shareware compilation disks as long as the fee does not exceed $7.00. Exception: a shareware compilation CD-ROM disk may charge more - please contact me for details.

===================================================================
=== Legal Stuff

The author of this software makes no warranty or representation either express or implied regarding the merchantability or fitness of this program for any particular purpose. This software is provided "as is" and the user is assuming the entire risk as to its quality and performance.

The author of this software will not be liable for direct, indirect, special, incidental or consequential damages resulting from any defect in the software or its documentation.

ProDOS, GS/OS and Apple are registered trademarks of Apple Computer, Inc.
Applesoft and Apple IIgs are trademarks of Apple Computer, Inc.
ORCA/M and ORCA/C are trademarks of The Byte Works, Inc.
MSDOS and Windows are probably registered trademarks of Microsoft Inc,
just as PC Transporter is probably a registered trademark of Applied
Engineering, and GNO/ME a trademark of Procyon, Inc.

===================================================================

This program is written in ORCA/C v2.10. This is the formal acknowledgement:

These programs contain material from the ORCA/C
Run-Time Libraries, copyright 1987-1994
by Byte Works, Inc. Used with permission.

===================================================================
	Peter Watson
	13 Ilios Close
	Forest Hill  Vic  3131
	Australia

	paw@acslink.net.au
	paw77@hotmail.com
===================================================================
